@material/notched-outline

What is @material/notched-outline?

@material/notched-outline is a package from Material Design Components (MDC) that provides a notched outline component. This component is typically used to create a visual effect around form fields, such as text fields, to indicate focus or selection. The notched outline is a key part of the Material Design guidelines for text fields.

What are @material/notched-outline's main functionalities?

Basic Notched Outline

This code sample demonstrates the basic structure of a notched outline with a floating label. The HTML structure includes the leading, notch, and trailing elements, while the CSS provides basic styling to visualize the notched outline.

{
  "html": "<div class='mdc-notched-outline'><div class='mdc-notched-outline__leading'></div><div class='mdc-notched-outline__notch'><span class='mdc-floating-label'>Label</span></div><div class='mdc-notched-outline__trailing'></div></div>",
  "css": ".mdc-notched-outline { position: relative; border: 1px solid; } .mdc-notched-outline__leading, .mdc-notched-outline__trailing { display: inline-block; } .mdc-notched-outline__notch { display: inline-block; padding: 0 8px; } .mdc-floating-label { position: absolute; top: -8px; left: 8px; }"
}

Notched Outline with Focus

This code sample shows a notched outline in a focused state. The `mdc-notched-outline--upgraded` and `mdc-notched-outline--notched` classes are used to apply styles that indicate focus, such as changing the border color to blue and floating the label above the notch.

{
  "html": "<div class='mdc-notched-outline mdc-notched-outline--upgraded mdc-notched-outline--notched'><div class='mdc-notched-outline__leading'></div><div class='mdc-notched-outline__notch'><span class='mdc-floating-label mdc-floating-label--float-above'>Label</span></div><div class='mdc-notched-outline__trailing'></div></div>",
  "css": ".mdc-notched-outline { position: relative; border: 1px solid; } .mdc-notched-outline--upgraded { border-color: blue; } .mdc-notched-outline--notched .mdc-notched-outline__notch { border-color: blue; } .mdc-floating-label--float-above { color: blue; }"
}

Other packages similar to @material/notched-outline

react-material-ui

React Material-UI is a popular library that implements Material Design components for React applications. It includes a TextField component with a notched outline feature, similar to @material/notched-outline. However, it is more comprehensive, offering a wide range of Material Design components beyond just the notched outline.

vuetify

Vuetify is a Material Design component framework for Vue.js. It provides a variety of components, including form inputs with notched outlines. Vuetify is similar to @material/notched-outline in that it adheres to Material Design guidelines, but it is tailored specifically for Vue.js applications.

angular-material

Angular Material is a UI component library for Angular developers that follows Material Design principles. It includes form field components with notched outlines, similar to @material/notched-outline. Angular Material is designed to integrate seamlessly with Angular applications, providing a consistent look and feel.

README

Notched Outline

The notched outline is a border around all sides of either a Text Field or Select component. This is used for the Outlined variant of either a Text Field or Select.

Design & API Documentation

• Material Design guidelines: Text Field Variations
• Demo with Notched Outline on Text Field

Installation

npm install @material/notched-outline

Basic Usage

HTML Structure

<span class="mdc-notched-outline">
  <span class="mdc-notched-outline__leading"></span>
  <span class="mdc-notched-outline__notch">
    <span class="mdc-floating-label">Label</span>
  </span>
  <span class="mdc-notched-outline__trailing"></span>
</span>

Note that the MDC Floating Label component is placed inside the notch element when used together with MDC Notched Outline.

See the MDC Text Field and MDC Select documentation for information on using Notched Outline in the context of those components.

Styles

@use "@material/notched-outline/mdc-notched-outline";

JavaScript Instantiation

import {MDCNotchedOutline} from '@material/notched-outline';

const notchedOutline = new MDCNotchedOutline(document.querySelector('.mdc-notched-outline'));

See Importing the JS component for more information on how to import JavaScript.

Style Customization

CSS Classes

CSS Class	Description
mdc-notched-outline	Mandatory. Container for the outline's sides and notch.
mdc-notched-outline--notched	Modifier class to open the notched outline.
mdc-notched-outline--no-label	Modifier class to use when the floating label is empty or not used.
mdc-notched-outline__leading	Mandatory. Element representing the leading side of the notched outline (before the notch).
mdc-notched-outline__notch	Mandatory. Element representing the notch.
mdc-notched-outline__trailing	Mandatory. Element representing the trailing side of the notched outline (after the notch).

Sass Mixins

Mixin	Description
color($color)	Customizes the border color of the notched outline.
stroke-width($width)	Changes notched outline width to a specified pixel value.
shape-radius($radius, $rtl-reflexive)	Sets the rounded shape to notched outline element with given radius size. Set $rtl-reflexive to true to flip radius values in RTL context, defaults to false.
floating-label-float-position($positionY, $positionX, $scale)	Sets the position and scale of the floating label inside the notched outline.

MDCNotchedOutline Properties and Methods

Method Signature	Description
notch(notchWidth: number) => void	Opens the notch with the specified width.
closeNotch() => void	Closes the notch, rendering a full outline.

Usage Within Frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a Notched Outline for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.

MDCNotchedOutlineAdapter

Method Signature	Description
addClass(className: string) => void	Adds a class to the notched outline element.
removeClass(className: string) => void	Removes a class from the notched outline element.
setNotchWidthProperty(width: number) => void	Sets the width of the notch in pixels.
removeNotchWidthProperty() => void	Removes the width property from the notch element.

MDCNotchedOutlineFoundation

Method Signature	Description
notch(notchWidth: number) => void	Adds the mdc-notched-outline--notched class and updates the notch element's style based on notchWidth.
closeNotch() => void	Removes the mdc-notched-outline--notched class.

Changelog

6.0.0 (2020-04-22)

Bug Fixes

• auto-init: Fixed issue with multiple default exports (#5464) (8ddd5c6)
• button: Fix outline & ink color according to spec guidance (#5268) (ee1a68c)
• button: Fixed parameter default value in height mixin (#5244) (b0cecf1)
• checkbox: change checkbox event type from change to click and add some logic for IE browser (#5316) (2e491de), closes #4893
• checkbox: Disabled state colors in IE11 high contrast mode (#5263) (d6a1d4b)
• checkbox: Replace unique-id with custom color hash functio… (#5404) (7be9e4a)
• checkbox: update disabled color values (#5209) (821871e)
• checkbox: Use secondary and on-secondary as default colors (b95172e), closes #5730
• chips: .d.ts file generated with syntax error (d154836)
• chips: .d.ts file generated with syntax error (#5577) (98f7faa)
• chips: Do not throw error if chip set becomes empty (#5290) (f978109)
• chips: Fix browser back nav in FF when removing chip with… (#5537) (a1a0deb)
• chips: Handle IE/Edge specific key names in keyboard navigation logic (3657f88)
• chips: Move touch target inside primary action (ad3bbf7)
• circular-progress: Add .npmignore file to ignore typescript files when publishing (#5801) (f172b0f), closes #5800
• circular-progress: fix determinate transition typo & 4 color keyframes (a301636)
• circular-progress: Fix naming in package.json and add to jsBundleFactory (86f7cad)
• circular-progress: Force LTR layout (6a40ef2)
• circular-progress: Switch mixins import to [@use](https://github.com/use) (098ae32)
• core: Fix canary release by excluding test files from default tsconfig (#5317) (c916008)
• data-table: change svg attribute name viewbox to viewBox (#5483) (#5493) (f3adce8)
• data-table: Fix pagination box height (eb28b6e)
• data-table: Fixed default feature targeting query params of sort mixins (e33c49e)
• data-table: Hover styles for sortable header cell (d580805)
• data-table: Reverse the arrow direction icon for column sorting (a7c827f)
• data-table: unable to redefine colors in class-based themi… (#5751) (4d48051)
• data-table: unable to redefine colors in class-based theming (4b45b66)
• dialog: Move aria roles from dialog root to dialog surface… (#5239) (c704b71)
• elevation: Update overlay color mixin (#5331) (b723dfa)
• fab: Add missing dep to fab package.json. (#5236) (e0f6fd9)
• fab: Add overflow: visible to make touch target visible in… (#5241) (5850080)
• fab: Adjust fab line-height (#5254) (525989b)
• fab: Adjust fab line-height to center text (#5258) (591a6ad)
• floatinglabel: Estimate hidden scroll width (#5448) (981ec9b)
• linear-progress: Temporary rollback of #5656 while updating downstream dependencies (9cf5e98)
• linear-progress: support aria attributes (#5248) (7084b40), closes #5248
• list: Ensure disabled colors apply to primary and secondary text (#5322) (878a08b)
• list: No longer emits action event when disabled item selected (f352d03), closes #5571
• menu-surface: Use margin_to_edge as a viewport margin in calculations for autopositioning. (4b04cdb)
• menusurface: open and closed events not fired when already opened or closed (9cff431)
• menusurface: synchronous quick menu does not close on button click (45a6615)
• notched-outline: Restore component test (#5449) (4269133)
• radio: update disabled color values (#5210) (491fddc)
• select: Deduplicate change events (4ad1274), closes #5570
• select: Do not fire change event on programmatic change (#5255) (ec72968)
• select: Fix notch outline width when floating (#5319) (1c494e5)
• slider: slider track not visible (#5512) (f2426d2)
• slider: two change events fired on each up (d10412c)
• slider: use secondary custom property color for slider container (#5132) (aa8e43e)
• slider: Visual bug when slider value is displayed as "-0" (3fc3ab5)
• snackbar: add explicit width for label to wrap in ie11 (#5497) (cd49033)
• snackbar: adjust mixins to meet spec (#5477) (f16f15b)
• switch: add transform transition to switch control to avoid overflow-x issues (8c11ea2)
• switch: always set track to transparent border (9a169f4)
• switch: fix strict generic checks (7f5e0c2)
• switch: handle aria-checked correctly. (#5202) (#5357) (d245a1a)
• switch: set track border to be transparent (#5323) (397905b)
• switch: use CSS custom properties for theming (d6315ef)
• testing: Revert change from #5299. (#5324) (5fb62be)
• textfield: add placeholder mixins and fix disabled colors (#5360) (0a40ced)
• textfield: add separate classes for leading/trailing icons (#5367) (70c708d)
• textfield: change root element to <label> (#5439) (d8d9502)
• textfield: clean up input padding (8639c26)
• textfield: hide filled-variant floating label at <52px (#5553) (5ff3380)
• textfield: IE11 label overlapping placeholder (781434a)
• textfield: incorrect mixin forward path (#5554) (3e782d8)
• textfield: move ripple to separate element (c541ebe)
• textfield: outlined trailing icon's position (#5496) (93e2288)
• textfield: prevent placeholder styles from collapsing with minifiers (d07c78d)
• add missing SASS dependencies (#5337) (d2ae6e1)
• textfield: remove absolute positioning from icons (1e13d1d)
• textfield: remove deprecated dense variant in favor of density (776291e), closes #4142
• textfield: use correct disabled colors for IE11 high contrast (5353985)
• Remove edge detection for CSS custom properties (#5264) (fe444ac)
• server-side rendering errors in linear progress and slider (7d0b983)

Code Refactoring

• migrate to the Sass module system (#5453) (faa9af3)
• grid-list: Deprecate component (#5499) (cf33f11)
• linear-progress: Restructure buffer DOM to allow translucent buffer (98b8434)
• linear-progress: Restructure buffer DOM to allow translucent buffer (9372e49)
• select: Fix alignment issues, upgrade anchor to interactive element (28d10a9), closes #5428
• touchtarget: Rename mdc-touch-target-component => mdc… (#5245) (afe0dd1)

Features

• button: Add disabled state color mixins (#5232) (b5eb51e)
• button: Add overflow ellipsis mixin (#5352) (47949b0)
• button: Expand outlined touch target to include side borders (ce6cb70)
• button: Setup elevation overlay (#5256) (3cbee6d)
• card: Add elevation overlay structure (#5282) (aa0eba4)
• checkbox: Add support for checkbox CSS-only indeterminate checkbox (b273afa)
• chips: Add chips styling (1db5c9f)
• chips: Add elevation overlay structure (#5279) (3e560b3)
• chips: Add focus{in|out} handlers (10af6cf)
• chips: Add keyCode support (82fa986)
• chips: Add trailing action feature targeting test (bec0659)
• chips: Announce when chips are removed (b3f70eb)
• chips: Consolidate interaction event handlers (#5251) (5729943)
• chips: Create trailing action business logic (9ebee4c)
• chips: Expose trailing action chip files (6b48781)
• chips: Restructure trailing action mixins (05f5e15)
• circular-progress: Add foundation methods to get isDeterminate and progress value (7d8f9c8)
• circular-progress: Add Sass styles and tests (bd33cb5)
• circular-progress: Add TS for foundation, adapter, component with tests (548b1d4)
• data-table: Add base styles to support pagination. (927fa90)
• data-table: Add foundation methods to support loading state. (e75deb8)
• data-table: Added styles for table in loading state (35a32aa)
• data-table: Added styles to support column sorting. (17b9699)
• data-table: Foundation changes to support column sorting (6ee0355)
• data-table: Set progress indicator styles based on table body height (c026422)
• dialog: Add elevation overlay structure (#5283) (b8bc4a2)
• dom: Add focus trap utility. (#5505) (63f357d)
• dom: Add keyboard support (5f24faa)
• dom: Create announcer utility (32c1df1)
• elevation: Add elevation overlay mixins (#5249) (b4cfdc4)
• elevation: Update elevation mixins (#5304) (ba879b6)
• fab: Add elevation overlay structure (#5278) (e89750d)
• fab: Add outline in high-contrast mode (deda86d)
• fab: Add support for increased touch target to mini FAB. (#5231) (0c4d8f3)
• floating-label: add feature targeting for styles (#5287) (b240bcc)
• form-field: Add support for space-between (e84b9c8), closes #5747
• formfield: add nowrap class/prop to MDC/MWC (c4b4bba)
• icon-button: Add disabled state color mixins (#5246) (7161170)
• iconbutton: Add icon button variant which supports toggling aria label. (f838c6e)
• line-ripple: add active/inactive states to line-ripple (b6c7f62)
• line-ripple: add feature targeting for styles (#5292) (391674a)
• linear-progress: Add foundation methods to fetch progress and determinate state. (4dc45af)
• menu: Add elevation overlay structure (#5280) (7fd17ce)
• menu: Add mixin to flatten menu top when opened-below anchor (1e17c49)
• menu-surface: Add support for flipping menu corner horizontally. (7b44824)
• notched-outline: add feature targeting for styles (#5289) (c483774)
• progress-indicator: Add common interface for progress indicators (#5564) (ea863cb)
• ripple: Reorganize ripple opacities (008c4d3)
• switch: Add elevation overlay structure (#5281) (50f110a)
• switch: Restructure DOM (#5312) (0ec1fab)
• text-field: Add disabled state color mixins (#5208) (66299b6)
• text-field: add feature targeting for styles (#5378) (e8a9936)
• text-field: Truncate floating label width w/ icons (c141801)
• textfield: add end-alignment (#5356) (847dd1a)
• textfield: add filled class variant (b70bc60)
• textfield: add forced LTR input (490fbdc)
• textfield: add prefix and suffix (6601d24), closes #1892
• Add index stylesheets to each MDC Web package (#5539) (1814866)
• Add index stylesheets to mdc-image-list and mdc-layout-gr… (#5546) (3a85313)
• Use @use syntax in material-components-web Sass file and… (#5573) (b4727e4)
• textfield: add specific label-floating class (a88c8e4)
• textfield: allow character counter to be moved outside of the textarea. (84e7ed5)
• textfield: Create float transition mixin (ca61b65)
• textfield: Limit notched outline max-width (0ab62a6)
• typography: add container baseline mixins for flexbox (69edc6e)

Reverts

• Revert "feat(switch): Add elevation overlay structure (#5281)" (#5329) (1fbf5bd), closes #5281 #5329
• "fix(checkbox): change checkbox event type from change to click and add some logic for IE browser" (ba30399)
• feat(chips): Consolidate interaction event handlers (#5251) (#5301) (5e45d77)
• fix(chips): Do not throw error if chip set becomes empty (#5300) (d10e8cd)
• fix(select): Do not fire change event on programmatic change (#5255) (#5302) (ad9dfe7)

BREAKING CHANGES

• select: HTML Markup significantly changed, see README; REMOVED adapter methods isSelectedTextFocused, getSelectedTextAttr, setSelectedTextAttr; ADDED adapter methods isSelectAnchorFocused, getSelectAnchorAttr, setSelectAnchorAttr; removed variables outlined-dense-label-position-y, icon-padding; added variables minimum-height-for-filled-label, filled-baseline-top, selected-text-height, anchor-padding-left, anchor-padding-left-with-leading-icon, anchor-padding-right.

• text-field: Redundant mixins mdc-text-field-textarea-fill-color, mdc-text-field-textarea-stroke-color, mdc-text-field-fullwidth-bottom-line-color removed. Instead, use mdc-text-field-fill-color, mdc-text-field-outline-color, and mdc-text-field-bottom-line-color respectively to achieve the same effect.

• textfield: mdc-text-field--dense and associated mixins/variables have been removed. Use the density() mixin instead.

• textfield: removed the following variables: $input-padding, $input-padding-top, $input-padding-bottom, $outlined-input-padding-top, $outlined-input-padding-bottom, $input-border-bottom

• linear-progress: DOM for linear progress buffer changed. MDCLinearProgressAdapter method getBuffer, getPrimaryBar, setStyle removed. MDCLinearProgressAdapter method setBufferBarStyle, setPrimaryBarStyle added.

• linear-progress: DOM for linear progress buffer changed. MDCLinearProgressAdapter method getBuffer, getPrimaryBar, setStyle removed. MDCLinearProgressAdapter method setBufferBarStyle, setPrimaryBarStyle added.

• typography: typography.baseline-top() and typography.baseline-bottom() are now private. Use typography.baseline() for containers and typography.text-baseline() for text with $top and $bottom params.

• chips: The touch target and text now appear inside the primary action element. Please see the readme for markup changes.

• textfield: filled text fields must include a <div class="mdc-text-field__ripple"></div>

• textfield: Filled textfields will no longer show a floating label at certain densities. This can be overridden by setting $mdc-text-field-minimum-height-for-filled-label: 40px

• chips: Both MDCChipAdapter and MDCChipSetAdapter have new methods. MDCChipSetFoundation event handlers now accept the corresponding chip event detail interface as the sole argument. The root property has been removed from the MDCChipRemovalEventDetail interface.

• line-ripple: mdc-line-ripple-color() mixin has been renamed to mdc-line-ripple-active-color()

• textfield: Default textfields must now specify mdc-text-field--filled. Disabled outlined textfields no longer have a shaded background. Height mixin no longer specifies a baseline override, use typography's baseline-top mixin.

• Four variables and a mixin in mdc-textfield were renamed to use a mdc-text-field- prefix when depended on via @import (formerly mdc-required-text-field-label-asterisk_, now required-label-asterisk_).

• textfield: icons must use .mdc-text-field__icon--leading or .mdc-text-field__icon--trailing classes. mdc-text-field-icon-color() mixin has been split into mdc-text-field-leading-icon-color() and mdc-text-field-trailing-icon-color().

• switch: Added setNativeControlAttr method in mdc-switch adapter.

• checkbox: remove event listener for 'change' and add event listener for 'click'.

• Add handleClick() method in foundation to handle click event.
• Add setCheck() method into component to change check status.

• switch: Switch DOM structure has changed. See switch README for details
• button: Variable $mdc-button-disabled-container-fill-color renamed to $mdc-button-disabled-container-color.
• Removed $edgeOptOut option from mdc-theme-prop() Sass mixin.
• chips: the handleInteraction and handleTrailingIconInteraction handlers have been removed from the MDCChipFoundation. The handleClick handler has been added to the MDCChipFoundation
• Adds new adapter methods to MDCLinearProgressAdapter.
• elevation: Functions moved into the _functions.scss file
• touchtarget: Renames mixin from mdc-touch-target-component => mdc-touch-target-margin
• grid-list: Per the deprecation notice for grid-list, this component has been removed from MDC-Web. Some of its functionalities are available in the MDC Image List package instead. It is recommended that you migrate to the mdc-image-list package to continue to receive new features and updates.